IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/u_man/cat1/par.z/par

Text File | 1998-10-20 | 26KB | 463 lines

PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



NNNNAAAAMMMMEEEE
     _pppp_aaaa_rrrr - process activity reporter / truss-like system call tracer

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_cccc_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_c_m_d _a_r_g_s ...]

     _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_cccc_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_----_pppp _p_i_d] [_----_pppp ...]

     _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_cccc_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_----_tttt _t_i_m_e]

     _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss]

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _pppp_aaaa_rrrr is a system utility program that reports on system call and
     scheduling activity for one or more processes.  _pppp_aaaa_rrrr can be used to trace
     the activity of a single process, a related group of processes, or the
     system as a whole.  See the _EEEE_XXXX_AAAA_MMMM_PPPP_LLLL_EEEE_SSSS section near the end for some
     examples on how par is commonly used.

     When tracing system calls, _pppp_aaaa_rrrr(1) prints a report showing all system
     calls made by the subject processes complete with arguments and return
     values.  In this mode, _pppp_aaaa_rrrr(1) also reports all signals delivered to the
     subject processes.  When tracing scheduler actions, _pppp_aaaa_rrrr(1) reports all
     scheduling events taking place in the system during the measurement
     period.  The report shows each time a process is put on a run queue,
     started on a processor, and descheduled from a processor.  All scheduling
     events are timestamped and, when available, include the reason for the
     action.

     _pppp_aaaa_rrrr(1) works by processing the output of _pppp_aaaa_dddd_cccc(1).  This can be done in
     two ways:  _pppp_aaaa_dddd_cccc can be run separately and the output saved in a file (to
     be fed to _pppp_aaaa_rrrr as a separate operation), or _pppp_aaaa_dddd_cccc can be invoked by _pppp_aaaa_rrrr to
     perform the data collection and reporting in one step.  _pppp_aaaa_rrrr can generate
     different reports from data collected by _pppp_aaaa_dddd_cccc depending on the reporting
     options that are specified.  The ability to generate different reports
     from a single set of data is one reason that it is often desirable to run
     the data collection as a separate step.

     There are three things that need to be specified on the _pppp_aaaa_rrrr command line:
     what information to report, what data should be collected, and what
     objects are to be monitored.  _pppp_aaaa_rrrr can be run without displaying any
     information (collection-only) or without collecting any event data
     (report-only).  Objects to be monitored may be running processes or
     commands that are started up specifically for the purpose of collecting
     event data.

     If an object is specified for monitoring (either a command to launch or
     an existing process), but no data collection or reporting options are
     specified, then _pppp_aaaa_rrrr defaults to collecting and reporting system call and
     signal data.





                                                                        PPPPaaaaggggeeee 1111






PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



     _DDDD_aaaa_tttt_aaaa _CCCC_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn _OOOO_pppp_tttt_iiii_oooo_nnnn_ssss

     These options should only be supplied when event data is to be collected
     by running a command or by tracing an already running process or set of
     processes.

     _----_ssss        Collect system call and signal data.

     _----_rrrr        Collect scheduler activity data.

     _----_kkkk        Collect disk i/o activity data.

     _----_iiii        Inherit tracing to forked children of object processes.

     _----_OOOO _f_i_l_e   Write raw event data to the specified _f_i_l_e.

     _RRRR_eeee_pppp_oooo_rrrr_tttt_iiii_nnnn_gggg _OOOO_pppp_tttt_iiii_oooo_nnnn_ssss

     Note that various options are meaningful only when the event data
     includes relevant information.  For example, requesting a report on
     system call activity is useless if no system call events are collected
     (with the _----_ssss option) or none are present in a file of previously
     collected data.

     _----_SSSS        Print a summary of system calls and signal counts.

     _----_SSSS_SSSS       Print both the summary of system call activity and a trace of
               each system call and signal action.

     _----_QQQQ        Print a summary of scheduling work.

     _----_QQQQ_QQQQ       Print both the summary of scheduling work and a trace of each
               scheduler operation.

     _----_QQQQ_QQQQ_QQQQ      In addition to the detailed scheduling trace, print the
               contents of the global run queue after each scheduler
               operation.

     _----_nnnn _s_y_s_c_a_l_l
               Show records for the specified system call, where the system
               call is specified by name or number.  This option may be
               specified multiple times.  Specifying this option automatically
               enables detailed system call reporting.

     _----_eeee _s_y_s_c_a_l_l
               Exclude the specified system call from the report.  This option
               may be specified multiple times.  Specifying this option
               automatically enables detailed system call reporting.

     Other options that control the format and content of reports are:





                                                                        PPPPaaaaggggeeee 2222






PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



     _----_AAAA        Show system call parameter data (e.g. from a _rrrr_eeee_aaaa_dddd call) in
               character format.  Non printable characters are output in hex.
               Normally, _pppp_aaaa_rrrr selects ASCII or binary format for data according
               to the data content.

     _----_aaaa _l_e_n    Set the maximum number of bytes printed in character format for
               data (e.g. from a _rrrr_eeee_aaaa_dddd call) to _l_e_n.  This value defaults to 30
               bytes.  The larger of the value for this option and the _----_bbbb
               option is used to inform _pppp_aaaa_dddd_cccc, if appropriate, how much data to
               collect (see the _----_IIII option of _pppp_aaaa_dddd_cccc).  The maximum value for
               this option is 4096 bytes.

     _----_BBBB        Show system call parameter data (e.g. from a _rrrr_eeee_aaaa_dddd call) in hex
               binary format.  Normally, _pppp_aaaa_rrrr selects ASCII or binary format
               for data according to the data content.

     _----_bbbb _l_e_n    Set the maximum number of bytes printed in binary format for
               data (e.g. from a _rrrr_eeee_aaaa_dddd call) to _l_e_n.  This value defaults to
               16.  The maximum value for this option is 4096 bytes.

     _----_cccc        Do not print CPU numbers in detailed trace reports.

     _----_dddd        Show each system call as two entries: one for when the system
               call is begun and a second when the system call completes.
               Normally _pppp_aaaa_rrrr displays system calls as a single line, showing
               input arguments, output arguments and return values.  The time
               displayed is the time of the start of the system call.  This
               compaction is done unless the duration of the system call
               exceeds a nominal threshold (25 microseconds by default).  With
               the _----_dddd option system calls are always displayed as beginning
               and ending operations.

     _----_llll        Show system call output in a long format that includes each
               process name and the CPU on which it is run.  By default _pppp_aaaa_rrrr
               will use this format whenever it is needed to avoid confusion;
               e.g. when multiple processes might appear in the report.
               Otherwise, _pppp_aaaa_rrrr uses a more compact format that does not show
               the process name or CPU number.  This option is only useful
               when a detailed report is requested; e.g. _----_QQQQ_QQQQ and/or _----_SSSS_SSSS.

     _----_oooo _f_i_l_e   Print all output (including errors) to _ffff_iiii_llll_eeee.  This is useful
               when monitoring a program that itself does output.

     _----_PPPP _p_i_d    List activity only for the process specified by _p_i_d.  Note that
               this is markedly different from the _----_pppp _p_i_d option that requests
               that the named _p_i_d be traced.  Thus one could request that
               processes 100 and 101 be traced, but only report system calls
               for process 101.  This option is typically specified when _pppp_aaaa_dddd_cccc
               has been used to collect data on a number of processes - often
               either by collecting for all processes on the system or all
               processes descended from a specified process.




                                                                        PPPPaaaaggggeeee 3333






PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



     _----_uuuu        Print event times as milliseconds and microseconds since the
               last displayed event.

     _OOOO_bbbb_jjjj_eeee_cccc_tttt _SSSS_pppp_eeee_cccc_iiii_ffff_iiii_cccc_aaaa_tttt_iiii_oooo_nnnn

     _----_pppp _p_i_d    Trace the process specified by _p_i_d. If the _----_iiii flag is specified
               then any child processes created by _p_i_d will also be traced.
               Multiple _----_pppp options may be given to trace multiple processes.
               In this mode, _pppp_aaaa_dddd_cccc(1) is automatically invoked by _pppp_aaaa_rrrr.

     _----_tttt _t_i_m_e   Terminate the trace after _t_i_m_e seconds. Primarily useful when
               tracing the system as a whole.

     _[[[[_c_o_m_m_a_n_d _a_r_g_u_m_e_n_t_s ..._]]]]
               Run the specified command with tracing enabled.  If the _----_iiii
               option is specified, any child processes that are created by
               _c_o_m_m_a_n_d will also be traced.  In this mode, _pppp_aaaa_dddd_cccc(1) is
               automatically invoked by _pppp_aaaa_rrrr.

     _n_o_t_h_i_n_g   If no specification of an object is given, all specified
               activity will be traced for the system as a whole.  Note that
               only the superuser can trace the system as a whole.  In this
               mode, _pppp_aaaa_dddd_cccc(1) is automatically invoked by _pppp_aaaa_rrrr.

     If no data collection options are specified and no object is specified,
     _pppp_aaaa_rrrr will read standard input as output from _pppp_aaaa_dddd_cccc and report the data
     according to the reporting options selected.

IIIINNNNTTTTEEEERRRRPPPPRRRREEEETTTTIIIINNNNGGGG TTTTHHHHEEEE RRRREEEEPPPPOOOORRRRTTTTSSSS
     _pppp_aaaa_rrrr generates several different reports.  Summary reports, requested with
     the _----_SSSS and _----_QQQQ options, are straightforward and are not described here.
     Other reports provide a detailed listing of the event data; they are
     composed of lines of the form:

          <_t_i_m_e>mS[<_c_p_u>] <_n_a_m_e>(<_p_i_d>): ...

     with the following explanations:

     <_t_i_m_e>    The time of the event in milliseconds relative to the start of
               data collection.  If the _----_uuuu option is supplied, <_t_i_m_e> will be
               followed by the number of microseconds since the last event
               (enclosed in parenthesis).

     <_c_p_u>     The CPU number the event was generated on.  This is displayed
               if a long listing is requested with the _----_llll option or if there
               is more than one CPU in the system that data is collected on.
               The _----_cccc option can be used to disable display of the CPU number.

     <_n_a_m_e>    The name of the process (as displayed by _pppp_ssss(1)).  This is only
               displayed for a long listing.





                                                                        PPPPaaaaggggeeee 4444






PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



     <_p_i_d>     The PID of the process.  This is only displayed for a long
               listing.

     The remaining information that _pppp_aaaa_rrrr prints depends on the type of event
     that is being reported.  For system calls each line is of the form:

           ... : <_s_y_s_c_a_l_l>(<_a_r_g_1>, <_a_r_g_2>, ..., <_a_r_g_N>) = <_r_e_s_u_l_t>

     with the following information:

     <_s_y_s_c_a_l_l> The system call name.  If the system call being displayed is
               split into 2 events, the event marking the end of the system
               call will have _EEEE_NNNN_DDDD_---- prepended to the name.  See below for some
               help in decoding system call names.  _pppp_aaaa_rrrr attempts to print an
               entire system call - input arguments, output arguments, and
               error return on a single line.  It does not do this if the _----_dddd
               option is given or if another event needs to be reported
               between the start and end of a call.

     <_a_r_g_N>    The system call arguments.  Various amounts of decoding of
               arguments is done.  Some system calls have complex arguments
               that have both input and output values.  If an entire system
               call is printed on one single line, these input/output
               arguments have the words _IIII_NNNN_:::: or _OOOO_UUUU_TTTT_:::: printed before the
               decoding of the argument.  Some complex indirect parameters are
               displayed symbolically using their C structure definition.
               Note that not all indirect parameter values are available; some
               are not returned by the operation system while others may not
               be copied out because doing so would exceed the maximum amount
               of indirect data to included in an event (see the _----_IIII option for
               _pppp_aaaa_dddd_cccc).

     <_r_e_s_u_l_t>  The error status or return value of the system call.  For
               system calls that simply return success or failure, _pppp_aaaa_rrrr prints
               _OOOO_KKKK for success, and the error value for failure.  System calls
               that return values have those values printed.

     Since _pppp_aaaa_rrrr's information comes straight from the operating system at the
     system call level, some calls that _pppp_aaaa_rrrr presents may not seem to
     correspond to the calls that the application made.  This is because some
     system calls are implemented in runtime libraries on top of more
     primitive system calls.  Some notable examples of this are:

     _wwww_aaaa_iiii_tttt_ssss_yyyy_ssss   is the underlying system call for all wait-like calls.  Its
               arguments are the same as _wwww_aaaa_iiii_tttt_iiii_dddd(2) except that it takes as a
               fifth argument a pointer to a _s_t_r_u_c_t _r_u_s_a_g_e.

     _????_xxxx_ssss_tttt_aaaa_tttt    These stat calls are the same as the application entry points
               except that the first argument is a version number.






                                                                        PPPPaaaaggggeeee 5555






PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



     _ssss_iiii_gggg_aaaa_cccc_tttt_iiii_oooo_nnnn is used to implement all type signal routines.  It takes one
               additional parameter than the application entry point - the
               address of the library handler that all signals funnel through.

     _ssss_iiii_gggg_rrrr_eeee_tttt_uuuu_rrrr_nnnn is used to return a process from its signal handler to the
               previous context.

     _ssss_iiii_gggg_pppp_oooo_llll_llll   is used to implement _ssss_iiii_gggg_wwww_aaaa_iiii_tttt_rrrr_tttt(3) and _ssss_iiii_gggg_tttt_iiii_mmmm_eeee_dddd_wwww_aaaa_iiii_tttt(3).

     _EEEE_RRRR_EEEE_SSSS_TTTT_AAAA_RRRR_TTTT  is returned when a system call should be automatically
               restarted after being interrupted by a signal (see _ssss_iiii_gggg_aaaa_cccc_tttt_iiii_oooo_nnnn).
               This error is never actually returned to the user but _pppp_aaaa_rrrr
               reports the re-invocation of a system call as an error.

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
          _pppp_aaaa_rrrr _llll_ssss _////

     Display a system call trace and summary for the command 'ls /'.  (_pppp_aaaa_rrrr
     supplies the implicit -sSS options because a command to launch was
     specified without any reporting or collection options.):

          apache% par ls /
          MISER      de         hosts      mnt        par.out    tmp        var
          RTMON      debug      hw         ns         proc       tmp_mnt
          TESTS      dev        lib        opt        proj       unix
          bin        doouf      lib32      out.1      rtmon.out  unix.benf
          build      etc        lib64      output.1   sbin       unix.orig
          build11    ficus      miser      par        stand      usr
              0mS[  1] was sent signal SIGUSR1
              0mS[  3] received signal SIGUSR1 (handler 0x10002560)
              0mS[  3] END-pause() errno = 4 (Interrupted function call)
              1mS[  3] sigreturn(0x7fff2b40) OK
              1mS[  3] execve(./ls, 0x7fff2f6c, 0x7fff2f78)
            262mS[  3] END-execve() errno = 2 (No such file or directory)
            262mS[  3] execve(/usr/sbin/ls, 0x7fff2f6c, 0x7fff2f78) errno = 2 (No such file or directory)
            263mS[  3] execve(/usr/bsd/ls, 0x7fff2f6c, 0x7fff2f78) errno = 2 (No such file or directory)
            264mS[  3] execve(/sbin/ls, 0x7fff2f6c, 0x7fff2f78)
            274mS[  3] END-execve() OK
            274mS[  3] open(/lib32/rld, O_RDONLY, 04) = 3
            275mS[  3] read(3, <7f 45 4c 46 01 02 01 00 00 00 00 00 00 00 00 00>..., 512) = 512
            276mS[  3] elfmap(3, 0x7fff2d54, 2) = 0xfb60000
            276mS[  3] close(3) OK
            279mS[  3] getpagesize() = 16384
            279mS[  3] sysinfo(_MIPS_SI_PROCESSORS, 0x7fff2dc0, 257) = 43
            281mS[  3] open(/dev/zero, O_RDONLY, 0) = 3
            282mS[  3] mmap(0xfbd4000, 16384, PROT_WRITE|PROT_READ, MAP_PRIVATE, 3, 0) = 0xfbd4000
            282mS[  3] close(3) OK
            ...

     Note that output from the command is intermixed with the system call
     report; the _----_oooo option can be used to direct the report to a file
     separately from any output generated by the command.  The report about



                                                                        PPPPaaaaggggeeee 6666






PPPPAAAARRRR((((1111))))                                                                  PPPPAAAARRRR((((1111))))



     the command receiving a SIGUSR1 signal is expected; this is done as part
     of the normal procedure for starting up a program with tracing.  Finally,
     note that many system call parameters are displayed symbolically and that
     the _i_n_d_i_r_e_c_t _v_a_l_u_e of many parameters is displayed; e.g. ``/lib32/rld''
     and ``/dev/zero'' for open.

          _pppp_aaaa_rrrr _----_rrrr_ssss_SSSS_SSSS_QQQQ_QQQQ _----_OOOO _llll_ssss_...._pppp_aaaa_dddd_cccc _llll_ssss _////

     Report on system calls and scheduling activities for the command 'ls /',
     and also record the raw event data in the file _l_s._p_a_d_c.

          _pppp_aaaa_rrrr _----_oooo _oooo_uuuu_tttt_ffff_iiii_llll_eeee _----_nnnn _oooo_pppp_eeee_nnnn _----_nnnn _cccc_llll_oooo_ssss_eeee _llll_ssss

     Trace only the open and close system calls.  Write the resulting output
     to _o_u_t_f_i_l_e.  Note that it is not necessary to specify _----_SSSS_SSSS options since
     they are implied by the _----_nnnn option.  Also, the _----_ssss option is not required
     because system calls are the default data to collect when a command is
     specified.

          _pppp_aaaa_rrrr _----_oooo _oooo_uuuu_tttt_ffff_iiii_llll_eeee _----_iiii _----_tttt _3333_0000 _----_pppp _1111

     Trace all processes started directly by process 1 (which is the iiiinnnniiiitttt
     process, the ancestor of all user processes) for thirty seconds, and
     store the report in the file _o_u_t_f_i_l_e.  Note that the _----_iiii option will cause
     only processes newly created by iiiinnnniiiitttt to be traced; i.e. it does not mark
     all existing child processes for tracing.

LLLLIIIIMMMMIIIITTTTAAAATTTTIIIIOOOONNNNSSSS
     To reduce system load, when collecting system call event data, system
     calls executed by _pppp_aaaa_dddd_cccc(1) and _rrrr_tttt_mmmm_oooo_nnnn_dddd_((((_1111_)))) are not recorded.  This can lead
     to some inexplicable gaps when tracing complete system activity.

     The process name associated with an event may be misleading.  This is
     because a process's name may change between the time an event is
     generated and the time the event collection process (_rrrr_tttt_mmmm_oooo_nnnn_dddd) checks for
     the name.  For example, a process may generate events then exit before
     _rrrr_tttt_mmmm_oooo_nnnn_dddd is able to query the system for the process name.  In this case
     the events will show up as being associated with a process without a
     name.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _pppp_aaaa_dddd_cccc(1), _rrrr_tttt_mmmm_oooo_nnnn_dddd(1).













                                                                        PPPPaaaaggggeeee 7777